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1.  PRELIMINARIES 


1.0.  Introduction 

LCPL  is  a program  for  solving  Linear  Complementarity  Problems 
by  Lemke's  method.  It  supersedes  the  "NULEMKE"  code  issued  by  SOL  in 
197U.  Considerable  care  has  been  taken  to  make  the  code  as  robust  as 
possible,  it  employs  more  error  checking  and  correction  facilities, 
recovery  procedures  and  more  diagnostics  than  the  earlier  code.  Scaling 
facilities  are  provided  for  badly  formulated  or  ill-conditioned  models. 
There  is  also  a much  larger  and  more  flexible  set  of  parameters  which 
can  be  set  by  the  user,  though  in  general  the  default  values  will  be 
satisfactory. 

This  document  gives  only  a description  of  the  use  of  the  code 
in  distributed  form.  The  program  itself,  and  the  procedures  for  changing 
it  to  solve  problems  of  larger  dimension  etc.,  are  described  in  the 
"Programmers  Guide  for  LCPL."  We  note  here,  however,  that  the  program 
is  all  in  FORTRAN  H for  IBM  36o/5?0  computers  and  is  WATFIV  compatible. 

1.1.  The  Linear  Complementarity  Problem 

An  LCP  is  a problem  of  the  form: 

Find  w and  z such  that 

m 

w = q + Mz  , v z = 0 , w,  z > 0 (l) 
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In  general  M is  required  to  have  sane  special  property,  such  as  positive 
r*mi -definiteness,  for  the  problem  to  have  a solution,  or  more  concretely, 
to  be  solvable  by  Lemke's  method  as  implemented  in  DCPL. 


Problems  of  type  (l)  arise  in  many  contexts,  perhaps  the  most  common 
being  quadratic  programming.  A solution  of  a semi-definite  program: 


, 1 1 T. 

min  c x + - x Dx 

C 

subject  to  Ax  > 0,  x > 0 


be  obtained  by  3olving  for  a Kuhn-Tucker  point: 


u 

v 


D -A1  rx 


A Oily 


T T 
x u + y v * 0 

x,y,u,v  > 0 


By  means  of  the  obvious  correspondence 


*■[’]’  * '[*,]•  q*[l]’  m=[I  '!  ]’ w 

we  have  a problem  of  type  (l).  Note  that  if  D is  positive  semi- 

definite,  so  is  M.  In  the  special  case  where  D is  zero  the  problem 

reduce-:  to  a linear  program. 

There  are  several  other  ways  in  which  LCP’s  arise,  seme 

directly  and  some  from  equivalent  problems.  The  user  is  referred  to 

R.W.  Cottle  and  u.B.  Dantzig,  ''Complementary  Pivot  Theory 
of  Mathematical  Programing,**  Linear  Algebra  and  its  Applications 
1,  103-125  (1568).  — 
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1.2.  Lemlee  • -3  Method 


Lemke's  method  solves  problems  of  type  (l)  when  M has  certain 
properties.  Several  sufficient  conditions  are  known,  but  a complete 
characterization  is  not  available  (see  Cottle  and  Dantzig,*.  Positive 
semi-definiteness  of  N,  or  the  case  where  M has  positive  principal 
minors , are  the  best  known  sufficient  conditions  and  cover  a wide  class 
of  prob Italic. 

In  outline,  Lemke's  method,  as  implemented  in  LCiJL,  appends  a 
dummy  column  and  variable  to  problem  (l): 

w = q + Mz  + e£  (5) 

whe-e  e has  +l*s  on  those  rows  where  qi  is  negative  (or  on  all  rows). 

£ is  then  pivoted  jjmnediately  into  the  basis  to  make  all  the  basic  (w) 

variables  non-negative.  ?ftis  eliminates  some  w^,  say  w^,  from  the 

basis  and  leads  to  a non-  :ia*-,v.ti  /e  solution  which  is  complementary  for 

all  but  one  pair.  The  complement  of  w , that  is  z , is  then  introduced 

P P 

into  the  basis  leading  to  a new  "almost  complementary"  solution.  This 
is  continued  until  either  £ leaves  the  basis  or  becomes  zero,  or  an 
unbounded,  ray  is  encountered  vheu  attempting  to  introduce  a variable 
into  the  bac.is  (again  ree  Cottle  and  Banvzig). 


1,5 . Implementation 

Internally  LCPL  stores  the  problem  in  the  form 
Iw  - Mz  - eC  * q 
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that  is  with  coefficient  matrix  [I,  -M,  -ei.  Only  the  non-zero 
coefficients  are  stored  in  packed  fora.  The  vector  e is  constructed 
internally  from  the  sign  pattern  of  the  given  q for  the  problem 
(an  optional  parameter  setting  allows  e to  be  a full  column  of  + l's 
if  desired)- 

The  basis  inverse  is  maintained  in  standard  product  form,  but 
uses  an  U1  decomposition  at  INVERT  time  when  a new  inverse  representation 
is  computed.  The  inversion  frequency  is  controlled  by  a parameter. 


1.4.  Recovery  Procedure. 

If  a problem  is  ill-conditioned  or  acme  tolerances  have  been 
set  to  unsuitable  values  it  is  numerically  possible  for  the  algorithm 
to  produce  two  error  conditions:  the  basic  .,olution  becomes  infeasible, 

that,  is  c cm  tains  a negative  value,  or  the  "basis"  may  be  detected  to 
be  singular  by  INVERT.  In  either  of  these  cases  the  following  recovery 
procedure  is  carried  out: 

l)  A non singular  complementary  basis  5,  containing  as  many 
columns  of  M in  common  with  the  old  basis  as  possible,  is 
constructed  (the  e column  is  always  removed). 

(2)  A transformed  problem  is  (notationaUy)  const’-ucted 

v = q + Mz 

where  q = B *q,  M = B~^M  and  w and  % are  a complementary 
permutation  of  the  original  w and  z.  Because  of  the  construction 


A * \ •>  **  i * H >%**'■ 


of  B this  is  a principal  transform  of  the  original  problem. 

Such  a transform  preserves  solvability  by  Lemke’s  method  ..f  the 
original  M is  positive  semi-definite  or  has  positive  principal 
minors . 

5 ) A new  column  e is  added  which  has  a +•!  on  every  row  where 
is  negative.  The  transformed  augmented  problem: 

w = q + Mr,  + e£ 

is  started  in  the  same  way  as  the  original  problem.  (Note:  Since 

the  code  keeps  the  original  M and  q throughout  we  wish  to  keep 
a representation  of  e in  terms  of  the  original  unit  basis.  Uiis 
is  immediately  to  hand  as  e'  - Se  which  over-writes  the  original  e). 


1.5 « Quadratic  Programming  Objective 

Throughout  the  algorithm  LCPL  prints  out  the  value  of  £ 

("DUMMY  Z" ) at  each  iteration.  If  the  problem  derives  from  a quadratic 

program#  set  up  as  in  (3),  the  user  may  specify  the  dimension  of  D 

(by  the  parameter  NQUAD)  and  the  value  of  c x + - x Dx  will  be  computed 

and  printed  on  completion.  In  this  caie  it  is  also  unnecessary  to 

T 

supply  the  columns  of  -A  . 
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2.  PROGRAM  INFUT 


2*0-  Introduction. 

There  are  two  parts  to  program  input;  the  parameter  list  and 
the  problem  input.  The  parameters  and  their  input  is  described  in 
Section  2.1.  The  matrix  M and  q are  input  in  a very  slightly 
modified  "MPS  format”  as  used  in  linear  programming.  In  addition  we 
may  specify  a starting  basis  as  specified  in  Section  2.3. 


2.1.  Parameters 

Parameters  are  changed  from  their  default  value  for  each 
problem  by  means  of  a FORTRAN  "NAMELIST”  input  from  the  card  reader. 
The  first  card  must  start  with  4PARAM  in  column  2 or  later)  each 
card  sn’-st  begin  with  a blank, and  the  list  must  be  terminated  by  AEHD. 

Examples. 

cols 
12  3 

*P  A R A M NQUAD=64,  IFSCAL=1,  *END 
4PARAM  AEND 

The  first  example  specifies  that  the  problem  is  a quadratic  program 
in  the  first  6k  variables  and  calls  for  scaling  of  M.  The  second 
example  leaves  all  parameters  at  their  default  values. 


o 


WWV’WJ.V ■' r A'VW 


We  group  the  parameters  into  the  following  groups: 

Run  Control: 

1TRLIM  (default  = 99999) 

Maximum  number  of  iterations  for  this  run  of  this  problem. 

INVFRQ  (default  = 30) 

Inversion  frequency 

ITCH  (default  = INVFRQ) 

Iteration  frequency  for  checking  the  relative  error  in  the 
current  basic  solution.  Defaulted  to  do  so  just  before  normal 
inversion.  (INVERT  automatically  carries  out  this  check 
after  inversion. ) 

IBFRQ  (default  - 99999 ) 

Iteration  frequency  for  writing  the  current  basis  to  the 
file  specified  by  KOUTB  (not  done  unless  JCOUTB  is  specified 
to  be  non-zero).  If  KOUTB  is  properly  specified  the 
final  basis  will  be  saved  regardless  of  the  value  of  IBFRQ. 


Input: 

fflP  (default  « 5) 

FORTRAN  logical  unit  number  for  reading  the  problem. 


7 


IFNEG 


(default  = l) 


Detemines  whether  to  change  -he  sign  of  the  input  matrix  M. 

With  the  default  setting  the  user  supplies  the  matrix  M ar.d 
-M  is  stored  to  collect  all  variables  on  the  left-hand  side 
as  in  (6).  If  the  user  supplies  -M  then  set  IFKEG  = 0, 

IFSCAL  (default  = 0) 

This  parameter  is  set  to  1 if  the  matrix  M is  to  be  scaled. 

If  scaling  is  performed  the  solution  (and  quadratic  objective 
function  value)  are  descaled  to  give  their  true  values.  Usually 
scaling  will  not  be  required. 

IFALLE  (default  * 0) 

If  the  parameter  is  set  to  1 the  dunny  column  e will  be 
constructed  with  a 1 in  every  position.  Not  reccsnended  for 
normal  use  since  this  Increases  the  density  of  the  transformations. 

KINB  (default  - 0) 

FORTRAN  logical  unit  number  for  reading  a basis.  With  the 
default  value  of  G no  basis  reading  will  be  attempted.  If 
jCTNB  is  greater  than  7 the  unit  is  rewound  before  reading. 

NQtlAD  (default  - 0) 

If  NQUAT  is  non-zero  the  pr'/blem  is  assumed  to  be  a quadratic  program 
in  the  fora  ( 2 ),  (?)  in  Section  1.1.  In  this  case  only  the  NQUAD 
columns  of  M corresponding  to  the  quadratic  variables  x 
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need  ce  supplied;  the  -A'  column  will  be  constructed  from 
the  last  '!  ,UAJ)  rows  of  the  column  supplied.  If  M is  non- 
square  and  Kvl'AD  is  not  correctly  specified  a fatal  error 
is  generated.  iCee  also  output. ) 


I0’JT  (default  * 0) 

With  the  default  setting  all  the  w and  z variables,  names 
and  values, are  printed.  If  I0U7  is  set  to  a non-zero  value 
only  the  basic  variables  are  printed  (in  sorted  order)  together 
with  the  row  names  and  the  origin*.',  right  hand  side  q. 

’.'QUAD  (default  = 0) 

If  NQUAD  has  sooe  non-zero  value  n the  first  n rows 
and  columns  of  M are  assumed  to  be  the  Hessian  of  a quadratic 
form,  as  in  (2).  Hie  value  of  the  quadratic  fora  will  be 
printed  out  after  the  w and  z variable  values  at  solution 
tine.  \See  also  Input  above. ) 

KOUTB  (default  = 0) 

FORTRAN  logical  unit  number  for  writing  the  basis  every  IBFRQ 
iterations  and  cn  termination.  No  basis  is  output  if  KOUTB 
is  zero.  Unit  KOUTB  is  rewound  before  and  after  writing 
if  KOUTB  is  greater  than  7. 
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Tolerances; 


>- 


if 


§R 

rf 


ZTOLZE  (default  = 1C_!+) 

Zero  tolerance  for  testing  feasibility.  Basic  variables  are 
non-negative  if  they  are  > -ZTOLZE.  Complementarity  is 
declared  if  ; ("DUMMY  ZV)  <_  ZTOLZE. 

ZTOLPV  (default  = 10-6) 

Absolute  pivot  tolerance. 

Q 

ZTOLRP  (default  = 10  ) 

Relative  pivot  tolerance  while  iterating.  A pivot  is  accepted 
if  its  absolute  value  is  greater  than  the  largest  absolute 
value  in  the  updated  column  multiplied  by  ZTOLRP.  If  this 
test  fails  INVERT  is  called  and  the  same  variable  is  considered 
again.  If  the  chosen  pivot  element  still  fails  the  test  it 
is  accepted.  Note  that  if  ZTOLRP  is  large  this  could  lead 
to  inverting  at  every  iteration.  If  ZTOLRP  is  too  small  the 
test  becomes  ineffective. 

ZTETA  (default  = 10-12) 

Tolerance  on  the  absolute  value  of  transformation  elements. 

Larger  values  may  give  sparser  transformations  but  at  great 
cost  to  accuracy  and  stability. 

ZTOLDA  (default  = 10-7) 

Tolerance  on  the  absolute  value  of  entries  in  the  matrix  M. 

Any  value  smaller  than  this  is  disregarded. 
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2.2.  Problem  Input 


The  M and  q defining  the  problem  are  read  from  unit  KINP 
in  slightly  modified  "MPS  format.''  The  card  images  required  are: 

NAME  Card 

This  has  "NAME"  in  columns  1 to  U and  the  (up  to  8 characters) 
problem  name  in  columns  15-22.  This  card  is  optional  but  highly 
desirable  (particular ly  for  checking  against  basis  names). 

BOWS  Card 

Has  "ROWS"  in  columns  1-k . 

Row  Names 

Each  row  is  assigned  a (unique)  name  of  up  to  8 characters,  one 
per  card,  in  columns  5-12.  Embedded  blanks  are  allowed  (unlike  MPS). 
Note  that  there  are  no  row  types  as  in  MPS  and  that  any  supplied  will 
be  ignored.  Column  1 must  be  blank. 

COLUMNS  Card 

Has  "COLUMNS"  in  columns  1-7. 

Matrix  Element 

The  non-zero  elements  of  M are  supplied  by  column.  All  the 
elements  of  a column  must  be  together.  Each  column  is  assigned  a 
(unique ) name  up  to  eight  characters.  The  format  is: 
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cols 

1-4 

5 - 12 

15  - 22 

25  - 36 

40  - 47 

50  - 6l 

blank 

column 

name 

row 

name 

element 

value 

second 

row 

name 

(optional) 

second 

element 

value 

(optional) 

Again  embedded  blanks  are  allowed  in  column  names. 

RHS  Card 

Has  "RHS"  in  columns  1-3. 

Right  Hand  Side  Elements 

The  right  hand  side  vector  (q)  may  be  given  a name,  which 
should  be  different  from  any  row  or  column  name.  The  elements  core  given 
in  the  same  format  as  the  matrix  elements.  Note  that  only  one  right 
hand  side  may  be  supplied.  If  an  attempt  is  made  to  input  more  than 
one,  the  non-reros  from  later  right  hand  sides  will  over-write  the 
earlier  values. 

ENDATA  Card 

Has  "ENDATA"  in  columns  1-6. 

Sample  input  is  shown  in  section  4.1. 

It  is  important  to  note  that  the  "w"  variables  are  assigned 
the  row  names  of  M,  and  the  variables  the  column  names,  nit.  iuamy 
column  e is  assigned  the  name  "DUMfY  Z",  as  is  the  dumay  variable 
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2.3*  Basis  Input 


A complementary,  or  almost  complementary,  basis  may  be  supplied 
from  unit  KINB.  For  each  complementary  pair  (w^z^),  where  the  z i 
is  basic, the  name  of  z ^ is  given,  otherwise  w^  is  assumed  basic.  If 
£ ("DUMMY  Z")  is  basic  the  name  of  the  w^  variable  in  the  non-ccmple- 
mentary  pair  it  replaces  is  given.  The  required  cards  and  formats  are: 

NAME  Card 

Has  "NAME"  in  columns  1 - 4 and  the  basis  name  in  columns  15-82. 

If  this  name  does  not  agree  with  the  problem  name,  or  the  name  card 
is  missing,  a warning  is  given. 

t 

A 

4 

i 

the  column  names  are  given  (one  per  j 

is  basic  there  must  be  & card  with  i 

a row  name  in  columns  15-22.  This  f 

l 

variable  £ replaces  in  the  basis.  J 

| 

| 

ENDATA  Card 

Has  "ENDATA"  in  columns  1-6. 

Note  that  if  the  basis  supplied  is  singular  or  infeasible 
the  program  will  enter  the  recovery  procedure  ("RECOVR" ) . If  naming 
errors  are  encountered  in  reading  the  basis  the  program  will  start  with 
the  partial  basis  found  (which  will  almost  certainly  trigger  a call  to 
RECOVR). 


Basis  Cards 

For  basic  columns  of  M 
card)  in  columns  5-12.  If  5 
"DUMMY  Z"  in  columns  5-12  and 
row  name  is  the  name  of  the  w 


2.4.  Problem  Size 


The  standard  version  of  LGPL  is  dimensioned  to  handle  problems 
of  up  to  350  rows,  with  up  to  4000  non-zero  matrix  elements  in 
[I,-M,-e].  Up  to  800C  eta  (transformation)  elements  are  allowed  for. 
If  these  dimensions  are  inadequate  the  program  must  be  changed  (see  the 
LCPL  programmer's  guide). 


2.5-  Multiple  Problems 

Any  number  of  problems  (each  preceded  by  parameter  cards ) may 
be  solved  in  sequence.  Note  that  all  parameters  are  reset  to  default 
values  before  each  new  set  of  parameters  and  'oblem  is  read. 


PROGRAM  OUTPUT 


> * 


3.0.  Introduction 

We  may  divide  the  program  output  into  three  categories.  Standard 
problem  description,  inversion  statistics,  the  iteration  log  and 
solution  print  are  described  in  Section  3*1*  Program  messages  and 
diagnostics  are  described  in  Section  3-2.  The  output  format 
for  a basis  written  on  unit  KOUTB  is  exactly  the  same  as  for  basis  output 
as  described  in  Section  2.3* 

3.1.  Standard  Output 

First  the  values  of  all  the  user  parameters  are  written  in 
NAMELIST  format  for  checking. 

(a)  Input  Information:  This  includes  the  problem  name  and  its  statistics 

-number  of  rows,  number  of  columns  of  M supplied,  number  of  non-zero 
M elements  and  density.  The  number  of  non-zero  (unit)  elements  in 
the  dummy  column  e constructed  is  also  given.  See  Section  k for 
examples. 

(b)  Inversion  Statistics;  These  include  number  of  nan-zeros  in  the  basis, 
structural  columns  in  the  basis,  the  number  of  non-zeros  in  the  L 
and  U factors  and  the  totals.  The  estimated  relative  error  in 

the  solution  for  the  new  inverse  is  also  given  (if  this  error  is  greater 
than  10  the  inversion  will  be  repeated  with  tighter  tolerances). 
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(c)  Iteration  Log:  Gives  for  each  iteration: 

ITCOUNT  = iteration  number 

{A  almost  complementary 
C complementary 

U unbounded  almost  complementary  ray 

DUMMY  Z = value  of  the  "dunray  variable”  £ 

VECIN  = name  of  column  entering  basis 
VECOUNT  = name  of  column  leaving  basis 
NETA  = number  of  etas  in  the  eta  file 

NEI£M  = number  of  elements  in  the  eta  file. 

(d)  Solution  Print -Out;  The  standard  option  gives  the  names  and  values 

of  all  the  "w"  and  ”zM  variables.  If  "DWMY  Z"  is  basic  its  value 
is  printed  after  the  ”zw  variables. 

If  I?kJT  - 1 only  the  basic  variables  are  printed  (in  sorted 
order)  together  vith  the  rear  names  and  the  original  q values. 

If  NQUAD  is  set  cTx  + ^ xTDx  will  be  evaluated  (see  fe)  in 
Section  l.l)  and  the  message 

QUADRATIC  OBJECTIVE  FUNCTION  VALUE  = xxxxx.xxxx 
is  printed. 

See  the  sample  run  output  for  example*. 
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3 . C- . Program  Mess'iges  and  Diagnostics 

The  following  informative  messages  mp.-.  be  printed,  depending 
on  parameter  settings,  problem  status,  etc. 

Input 

SPLIT  VECTOR  'name' 

A column  with  the  same  'name'  was  encounterea  'arlier.  The  input 
deck  is  probably  corrupted.  Input  continues  nowever. 

NO  MATCH  FOR  Rcw  'rcvname'  AT  COUJMN  'colr^-e* 

Column  'colnarae*  contains  a nonzero  cw:  an  unidentifiable  row 
' rowname ' . Check  alignment  of  row  names  in  rows  and  columns  sections. 
Tnis  is  a fatal  error. 

NUMBER  OF  MATRIX  ELEMENTS  'number'  EXCEEDS  NAMAX -ABORT 

The  program  dimensions  for  At*}  and  IA(* ) must  be  increased 
to  solve  the  problem.  Fatal  error.  Standard  KAMA,  is  4000.  Message  can 
alro  occur  in  RECOVR. 

MATRIX  NOT  SQUARE  AND  NQUAD  INCORRECTLY  SPECIFIED-PROBLEM  ABANDONED. 

The  number  of  structural  columns  supplied  is  not  equal  to 
either  IfRCW  or  the  specified  value  of  NQUAD.  M cannot  therefore  be 
properly  constructed  to  be  square.  Fatal  error. 
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NQUAD  COLUMNS  ONLY  SUPPLIED- WILL  ATTEMPT  TO  FILM  ' number  * EXTRA  COKJMNS 
OF  CONSTRAINT  MATRIX  TRANSPOSE 


»■ 


The  problem  is  assumed  to  be  a quadratic  program  of  form  (g) 

T 

as  in  Section  I. I.  The  columns  of  -A  are  given  the  same  names  as  the  rows  of  A. 
TRANSPOSE  COLUMNS  ADDED  TO  MATRIX 
-AT' 

added  to  make  M square. 

0 

EMPTY  R0W  ‘row  no. ' SNCOUNTERED-ABANDONING  PROBLEM 

An  empty  row  (number  'row  no.')  has  been  encountered  in  trying 

T 

to  construct  -A  . Empty  columns  are  not  allowed.  Fatal  error. 

MATRIX  SCALING  CALLED  FOR 

IFSCAL  ms  set  equal  to  a non-zero  value  and  M will  be  scaled. 

INITIAL  SUM  OF  SQUARES  OF  EXPONENTS  = • number' 

Initial  status  of  matrix  before  scaling  by  exponent. 

NEW  SUM  OF  SQUARES  OF  EXPONENTS  = ‘ntu*er’. 

Status  of  matrix  after  scaling.  All  scaling  is  done  cn 
exponents  only,  and  hence  scaling  factors  are  powers  of  1 6.  If  the  matrix 
was  well  scaled  to  begin  with,  the  new  sum  of  squares  syy  be  larger 
than  the  old. 


i 
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SINGULAR  M MATRIX-NO  SCALING  PERFORMED 


The  scaling  routine  detected  a zero  row  or  column.  The  run 
will  continue  but  normal  termination  is  unlikely. 

DUM4Y  COLUMN  WITH  'number'  ELEMENTS  CONSTRUCTED 

There  are  negative  elements  in  the  q vector  and  a dummy 
column  has  been  constructed  for  ’’ DUMMY  Z". 

PROBLEM  HAS  TRIVIAL  SOLUTION 

Either  q is  non-negative  or  the  given  starting  basis  yields 
a feasible  complementary  solution.  No  dummy  column  is  extracted 
and  tLo  solution  is  printed  out. 

STARTING  BASIS  WILL  BE  READ  FROM  FILE  'number'. 

KINB  was  specified  to  be  'number' 

BASIS  GIVEN  NOT  FEASIBLE,  WILL  ENTER  RECOVR 

The  given  basis  (complementary  or  almost  complementary ) is 
infeaaiblc.  The  recovery  routine  is  called  to  construct  a new  baeis 
and  dummy  column. 

WARNING  - BAl'IS  NAME  CARD  MISSING 


W'  WARNING-BASIS  HAS  NAME  * name'  -DIFFERENT  FROM  PROBLEM 

Warning  messages  on  reading  a basis.  May  not  be  the  correct 
basis  for  the  problem.  Run  continues. 

NO  MATCH  FOR  VECTOR 

The  basis  file  has  a vector  name  not  found  in  the  problem. 

Vector  ignored  and  run  continues.  Will  almost  certainly  yield  singular 
or  infeasible  basis  and  a call  to  the  recovery  routine. 

NO  MATCH  FOR  ROW  'rovnam'  TO  SWAP  WITH  DUMMY  Z 
„ The  row  name  'rownam'  cannot  be  found  when  leading  the  basis 

and  the  "DUMMY  Z"  variable  is  not  put  in  the  basis. 

| The  run  will  continue. 

SPURIOUS  CARD  IN  BASIS  FILE-’ text' -ABORT 

An  unrecognizable  card  in  the  basis  file  - fatal  error. 

ERROR  IN  TRYING  TO  READ  BASIS  FROM  FILE  'number* -CHECK  JCL  AND  PARAMETERS 
RIJN  ABORTED 

A FORTRAN  read  error  has  occurred  trying  to  read  file  KtNB. 

Fatal  error.. 

4 Run  Time  Messages 

| PEAS  LOST  ON  ROW  'row  no.”  VAR  'variable  name'  * 'value' 

| A loss  of  feasibility  is  detected  when  attempting  to  choose 

- 1 a pivot  rev.  Call  to  RECCVR  is  triggered. 

-=1  if 
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MAT RDC  SINGUIAR-VECTOR  ‘col’-jnn  name*  REMOVED 

INVERT  has  detected  a singularity.  See  below. 

INVERT  FAILS.  WILL  ATTEMPT  TO  RECOVR 

One  or  more  singularities  were  detected  by  INVERT.  A call  to 

Tl 

RECOVR  is  triggered. 

INSUFFICIENT  ETA  SPACE  TO  INVERT-RUN  ABANDONED 
INCREASE  ETA  SPACE  AND  NEMAX 

The  arrays  IE(*)  and  E(*)  in  the  program  must  be  increased 
from  their  current  dimension  (standard  value  is  NEfiAX  = 6000) . 

RELATIVE  ERROR  IN  X = ’value* 

Error  ronitoring  message  given  every  ITCH  iterations  (standard) 
is  just  before  INVERT) 


ITERATION  LIMIT  EXCEEDED 

ITRLIM  iteration*  have  been  performed.  End  of  run. 


BASIS  WRITTEN  ON  FILE  'number'  at  ITERATION  ’number’ 
The  basis  has  been  written  on  file  KOUTB. 
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."Nswaow*. 


NONCOMP  I£MENT ARY  PAIR  NOT  DEFINED,  BUT  DUMMY  Z IN  BASIS,  UNRESOLVABLE 


U- 


ERROR -NO  BASIS  SAVED. 

The  solution  is  supposedly  complementary  but  DUMMY  Z is  ba3ic. 
Highly  unlikely  unless  program  corrupted. 


Recovery  Routine 

FATAL  ERROR-’ number*  BASIC  VECTORS 

The  problem  does  not  have  NRCfc  basic  vectors.  Probably  due  to 
corrupted  program  or  split  vectors. 

RECOVERY  FAILS -CANNOT  FIND  COMPIEMENTARY  BASIS 
Probably  due  to  split  vectors. 


COMPIEMENTARY  BASIS  FOUND 

RECOVR  has  found  a new  complementary  basis. 

FEAS  COMP  BASIS  ARRIVED  AT  IN  RECOVR 

RECOVR  has  (fortuitously)  found  the  complementary  basis  it 
has  constructed  to  be  feasible.  Problem  solved. 

HEW  DUMMY  COLUWt  CONSTRUCTED 

RECOVR  has  constructed  a new  dusmy  column  and  determined  a 
pivot  row  which  will  give  a feasible  almost  complementary  solution. 
Returns  to  normal  algorithm. 
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!•.  SAMPLE  HUNS 


h.c . Prcblem  Descri pr. ions 


Assume  the  user  wishes  to  ::-»ive  the  following  quadratic  programming 


problems : 


1)  min  Xj  s.t.  2x ^ < (>,  2x ^ * x„  < h, 


*1»  > 0 , 


2)  min  2x^  * .Vx^x  , ♦ ?x^  * ? x,x ^ * x*  - i5x ^ - 6x?  - *ix. 


s.t.  xi  4 x2  + 2x$  - 5'  xl»  x2'  x3  ^ 0 > 


,,  . 1 2 12 

3)  min  2 xi  * xixp  4 J X2  " X1 


s.t.  x1>xg  > 0 


First  the  user  must  formulate  those  as  linear  complementarity  problems: 


2 ? 


0 2 


-1  -2 


' 21 
» u 


0 


1 -1 


-1  3 


D *C) 


and  put  them  in  suitable  MPS-type  format  as  follcas 
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4.1.  Program  Input 
&PARAN  NQURD=2  *&END 


NAME 

ROWS 

Ml 

M2 

M3 

W4 

COLUMNS 

TEST  1 

21 

Ml 

2.0 

21 

W4 

-2.0 

22 

M3 

-3.0 

23 

Ml 

2.0 

24 

RHS 

Ml 

2.0 

RHS 

ENDATA 

W3 

6.0 

&PARRM 

NQUAD-3  j&END 

NAME 

ROWS 

Ml 

M2 

M3 

W4 

COLUMNS 

TEST2 

21 

Ml 

4.0 

21 

M3 

2.0 

22 

Ml 

2.0 

22 

W4 

-1.0 

23 

Ml 

2.0 

23 

W4 

-2.0 

24 

Ml 

1.0 

24 

RHS 

M3 

2.0 

RHS 

Ml 

-8.0 

RHS 

ENDATA 

M3 

-4.0 

&PARAM  NGUR0=2,&END 
NAME  TEST3 

ROWS 

W1 

M2 

COLUMNS 

Z1  W1  1.0 

22  Mt  -1.0 

RHS 

RHS  Ml  -1.0 

ENDATA 


W3 

W4 

W2 

M2 


W4 


W2 

W4 

W2 

W3 

W2 


W2 

W4 


W2 

W2 

W2 


-2.0 

-1.0 

3.0 

1.0 


4.0 


2.0 

-1.0 

4.0 

2.0 

1.0 


-6.0 

3.0 


-1.0 

1.0 

0.0 
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k.2.  Program  Output 
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U . 3 . Use  of  the  WQUAD  Input  Option 


To  illustrate  use  of  the  NSUAD  input  option  for  quadratic  programs 

we  reconsider  problem  TE3T2  from  the  previous  section.  This  is  a QP  in 

three  variables  with  only  one  constraint.  In  Section  U.l  the  problem 

T 

is  set  up  to  include  the  entire  M matrix  including  the  -A  column 
from  the  constraint  transpose.  Below  we  enter  only  the  first  three 
columns  of  M.  The  fourth  column  is  constructed  internally  and  given 
the  name  "W4".  This  naming  can  cause  some  slight  confusion  in  the 
iteration  log,  but  it  seems  reasonable  to  name  these  dual  variables 
after  the  rows  to  which  they  correspond. 
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